Eclipse Platform
Pre-release 3.0

org.eclipse.ui.commands
Interface ICommand

All Superinterfaces:
Comparable

public interface ICommand
extends Comparable

An instance of ICommand is a handle representing a command as defined by the extension point org.eclipse.ui.commands. The identifier of the handle is identifier of the command being represented.

An instance of ICommand can be obtained from an instance of ICommandManager for any identifier, whether or not a command with that identifier defined in the plugin registry.

The handle-based nature of this API allows it to work well with runtime plugin activation and deactivation, which causes dynamic changes to the plugin registry, and therefore, potentially, dynamic changes to the set of command definitions.

This interface is not intended to be extended or implemented by clients.

EXPERIMENTAL

Since:
3.0
See Also:
ICommandListener, ICommandManager, IKeySequenceBinding

Method Summary
 void addCommandListener(ICommandListener commandListener)
          Registers an instance of ICommandListener to listen for changes to attributes of this instance.
 String getCategoryId()
           Returns the identifier of the category of the command represented by this handle.
 List getContextBindings()
           Returns the list of activity bindings for this handle.
 String getDescription()
           Returns the description of the command represented by this handle, suitable for display to the user.
 String getId()
          Returns the identifier of this handle.
 List getImageBindings()
           Returns the list of image bindings for this handle.
 List getKeySequenceBindings()
           Returns the list of key sequence bindings for this handle.
 String getName()
           Returns the name of the command represented by this handle, suitable for display to the user.
 boolean isActive()
           Returns whether or not this command is active.
 boolean isDefined()
           Returns whether or not the command represented by this handle is defined.
 boolean isEnabled()
           Returns whether or not this command is enabled.
 void removeCommandListener(ICommandListener commandListener)
          Unregisters an instance of ICommandListener listening for changes to attributes of this instance.
 
Methods inherited from interface java.lang.Comparable
compareTo
 

Method Detail

addCommandListener

public void addCommandListener(ICommandListener commandListener)
Registers an instance of ICommandListener to listen for changes to attributes of this instance.

Parameters:
commandListener - the instance of ICommandListener to register. Must not be null. If an attempt is made to register an instance of ICommandListener which is already registered with this instance, no operation is performed.

getContextBindings

public List getContextBindings()

Returns the list of activity bindings for this handle. This method will return all activity bindings for this handle's identifier, whether or not the command represented by this handle is defined.

Notification is sent to all registered listeners if this attribute changes.

Returns:
the list of activity bindings. This list may be empty, but is guaranteed not to be null. If this list is not empty, it is guaranteed to only contain instances of IActivityBinding.

getCategoryId

public String getCategoryId()
                     throws NotDefinedException

Returns the identifier of the category of the command represented by this handle.

Notification is sent to all registered listeners if this attribute changes.

Returns:
the identifier of the category of the command represented by this handle. May be null.
Throws:
NotDefinedException - if the command represented by this handle is not defined.

getDescription

public String getDescription()
                      throws NotDefinedException

Returns the description of the command represented by this handle, suitable for display to the user.

Notification is sent to all registered listeners if this attribute changes.

Returns:
the description of the command represented by this handle. Guaranteed not to be null.
Throws:
NotDefinedException - if the command represented by this handle is not defined.

getId

public String getId()
Returns the identifier of this handle.

Returns:
the identifier of this handle. Guaranteed not to be null.

getImageBindings

public List getImageBindings()

Returns the list of image bindings for this handle. This method will return all image bindings for this handle's identifier, whether or not the command represented by this handle is defined.

Notification is sent to all registered listeners if this attribute changes.

Returns:
the list of image bindings. This list may be empty, but is guaranteed not to be null. If this list is not empty, it is guaranteed to only contain instances of IImageBinding.

getKeySequenceBindings

public List getKeySequenceBindings()

Returns the list of key sequence bindings for this handle. This method will return all key sequence bindings for this handle's identifier, whether or not the command represented by this handle is defined.

Notification is sent to all registered listeners if this attribute changes.

Returns:
the list of key sequence bindings. This list may be empty, but is guaranteed not to be null. If this list is not empty, it is guaranteed to only contain instances of IKeySequenceBinding.

getName

public String getName()
               throws NotDefinedException

Returns the name of the command represented by this handle, suitable for display to the user.

Notification is sent to all registered listeners if this attribute changes.

Returns:
the name of the command represented by this handle. Guaranteed not to be null.
Throws:
NotDefinedException - if the command represented by this handle is not defined.

isActive

public boolean isActive()

Returns whether or not this command is active. Instances of ICommand are activated and deactivated by the instance of ICommandManager from whence they were brokered.

Notification is sent to all registered listeners if this attribute changes.

Returns:
true, iff this command is active.

isDefined

public boolean isDefined()

Returns whether or not the command represented by this handle is defined.

Notification is sent to all registered listeners if this attribute changes.

Returns:
true, iff the command represented by this handle is defined.

isEnabled

public boolean isEnabled()

Returns whether or not this command is enabled. Instances of ICommand are enabled and disabled by the instance of ICommandManager from whence they were brokered.

Notification is sent to all registered listeners if this attribute changes.

Returns:
true, iff this command is enabled.

removeCommandListener

public void removeCommandListener(ICommandListener commandListener)
Unregisters an instance of ICommandListener listening for changes to attributes of this instance.

Parameters:
commandListener - the instance of ICommandListener to unregister. Must not be null. If an attempt is made to unregister an instance of ICommandListener which is not already registered with this instance, no operation is performed.

Eclipse Platform
Pre-release 3.0

Copyright (c) IBM Corp. and others 2000, 2003. All Rights Reserved.